#region license
/*
 * Copyright (C) 2007 CchenSoft.com
 * 
 * This library is free software; you can redistribute it and/or modify it 
 * under the terms of the GNU Lesser General Public License 2.1 or later, as
 * published by the Free Software Foundation. See the included License.txt
 * or http://www.gnu.org/copyleft/lesser.html for details.
 * 
 * Author: Billy Zhang
 */
#endregion

using System.Collections;
using System.Collections.Generic;

using CchenSoft.Workflow.Spi;
using CchenSoft.Workflow.Loader;
using CchenSoft.Workflow.Query;
using CchenSoft.Workflow.Config;

namespace CchenSoft.Workflow
{
    public class WorkflowConstants
    {
        public const string BSF_COL = "col";
        public const string BSF_LANGUAGE = "language";
        public const string BSF_ROW = "row";
        public const string BSF_SCRIPT = "script";
        public const string BSF_SOURCE = "source";
        public const string BSH_SCRIPT = "script";

        // statics
        public const string CLASS_NAME = "class.name";
        public const string EJB_LOCATION = "ejb.location";
        public const string JNDI_LOCATION = "jndi.location";
    }

    public interface IWorkflow
    {
        //~ Instance fields ////////////////////////////////////////////////////////

        //~ Methods ////////////////////////////////////////////////////////////////

        /**
         * @deprecated use {@link #getAvailableActions(long, Map)}  with an empty Map instead.
         */
        int[] GetAvailableActions();

        /**
         * Returns a Collection of Step objects that are the current steps of the specified workflow instance.
         *
         * @param id The workflow instance id.
         * @return The steps that the workflow instance is currently in.
         */
        IList<IStep> GetCurrentSteps();

        /**
         * Return the state of the specified workflow instance id.
         * @param id The workflow instance id.
         * @return int The state id of the specified workflow
         */
        int GetEntryState();

        /**
         * Returns a list of all steps that are completed for the given workflow instance id.
         *
         * @param id The workflow instance id.
         * @return a List of Steps
         * @see com.opensymphony.workflow.spi.Step
         */
        IList<IStep> GetHistorySteps();

        /**
         * Get a collection (Strings) of currently defined permissions for the specified workflow instance.
         * @param id the workflow instance id.
         * @return A List of permissions specified currently (a permission is a string name).
         * @deprecated use {@link #getSecurityPermissions(long, java.util.Map)} with a null map instead.
         */
        IList GetSecurityPermissions();

        /**
         * Get a collection (Strings) of currently defined permissions for the specified workflow instance.
         * @param id id the workflow instance id.
         * @param inputs inputs The inputs to the workflow instance.
         * @return A List of permissions specified currently (a permission is a string name).
         */
        IList GetSecurityPermissions(IDictionary inputs);

        /**
         * Get the workflow descriptor for the specified workflow name.
         * @param workflowName The workflow name.
         */
        WorkflowDescriptor Descriptor { get; }

        long WorkflowId { get; set; }

        /**
         * Get the name of the specified workflow instance.
         * @param id the workflow instance id.
         */
        string WorkflowName { get; }

        /**
         * Check if the calling user has enough permissions to initialise the specified workflow.
         * @param workflowName The name of the workflow to check.
         * @param initialStep The id of the initial state to check.
         * @return true if the user can successfully call initialize, false otherwise.
         */
        bool CanInitialize(int initialStep);

        /**
        * Check if the state of the specified workflow instance can be changed to the new specified one.
        * @param id The workflow instance id.
        * @param newState The new state id.
        * @return true if the state of the workflow can be modified, false otherwise.
        */
        bool CanModifyEntryState(int newState);

        /**
         * Modify the state of the specified workflow instance.
         * @param id The workflow instance id.
         * @param newState the new state to change the workflow instance to.
         * If the new state is {@link com.opensymphony.workflow.spi.WorkflowEntry.KILLED}
         * or {@link com.opensymphony.workflow.spi.WorkflowEntry.COMPLETED}
         * then all current steps are moved to history steps. If the new state is
         */
        void ChangeEntryState(int newState);

        /**
         * Perform an action on the specified workflow instance.
         * @param id The workflow instance id.
         * @param actionId The action id to perform (action id's are listed in the workflow descriptor).
         * @param inputs The inputs to the workflow instance.
         * @throws InvalidInputException if a validator is specified and an input is invalid.
         * @throws InvalidActionException if the action is invalid for the specified workflow
         * instance's current state.
         */
        void DoAction(int actionId, IDictionary inputs);

        /**
         * Executes a special trigger-function using the context of the given workflow instance id.
         * Note that this method is exposed for Quartz trigger jobs, user code should never call it.
         * @param id The workflow instance id
         * @param triggerId The id of the speciail trigger-function
         */
        void ExecuteTriggerFunction(int triggerId);

        /**
        * Initializes a workflow so that it can begin processing. A workflow must be initialized before it can
        * begin any sort of activity. It can only be initialized once.
        *
        * @param workflowName The workflow name to create and initialize an instance for
        * @param initialAction The initial step to start the workflow
        * @param inputs The inputs entered by the end-user
        * @throws InvalidRoleException if the user can't start this function
        * @throws InvalidInputException if a validator is specified and an input is invalid.
        * @throws InvalidActionException if the specified initial action is invalid for the specified workflow.
        */
        long Initialize(int initialAction, IDictionary inputs);

        /**
         * Get the available actions for the specified workflow instance.
         * @ejb.interface-method
         * @param id The workflow instance id.
         * @param inputs The inputs map to pass on to conditions
         * @return An array of action id's that can be performed on the specified entry
         * @throws IllegalArgumentException if the specified id does not exist, or if its workflow
         * descriptor is no longer available or has become invalid.
         */
        int[] GetAvailableActions(IDictionary inputs);

        /**
         * Determine if a particular workflow can be initialized.
         * @param workflowName The workflow name to check.
         * @param initialAction The potential initial action.
         * @param inputs The inputs to check.
         * @return true if the workflow can be initialized, false otherwise.
         */
        bool CanInitialize(int initialAction, IDictionary inputs);

    }
}
